home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD v1.1 / Amiga Developer CD v1.1 - May 1996 (1996)(Schatztruhe)[!].iso / Contributions / IAM / Networking / Envoy-2.0 / doc / services.doc < prev    next >
Text File  |  1994-12-22  |  3KB  |  101 lines
  1. TABLE OF CONTENTS
  2.  
  3. services.library/FindService
  4. services.library/LoseService
  5. services.library/FindService                     services.library/FindService
  6.  
  7.    NAME
  8.        FindServiceA -- Connect to a Service.
  9.        FindService -- varargs stub for FindServiceA().
  10.  
  11.    SYNOPSIS
  12.        remote_entity = FindServiceA(remotehost, svcname, srcentity, taglist);
  13.        D0                           A0          A1       A2         A3
  14.  
  15.        struct Entity *FindServiceA(STRPTR, STRPTR, struct Entity *,
  16.                struct TagItem *);
  17.  
  18.        remote_entity = FindService(remoteHost, svcname,srcentity,tag1, ...);
  19.  
  20.        struct Entity *FindServiceA(STRPTR, STRPTR, struct Entity *,
  21.                Tag, ...);
  22.  
  23.    FUNCTION
  24.        Attemps to locate a certain service on a given host.
  25.  
  26.    INPUTS
  27.        remotehost - Pointer to a NULL-terminated string that is the name
  28.            of the host on which the service you want to use is provided.
  29.            NULL implies the local host.
  30.        servicename - Pointer to a NULL-terminated string that is the name
  31.            of the service you want to connect to.
  32.        srcentity - an Entity returned by nipc.library/CreateEntity() that
  33.            you wish to use as the 'near' side of the communications path.
  34.        taglist - tag item list to search (may be NULL).
  35.  
  36.    TAGS
  37.        Tags for use with FindService():
  38.  
  39.        FSVC_UserName (STRPTR) - Specifies the name of the user who is trying
  40.            to use the service.  If NULL, or the tag is not specified, the
  41.            call will only be able to connect to a service marked as public
  42.            on the remote machine.
  43.  
  44.        FSVC_PassWord (STRPTR) - The password of the user who is trying to use
  45.            the service.  Only useful in conjunction with FSVC_UserName.
  46.  
  47.        FSVC_Error (ULONG *) - If specified, a pointer to a ULONG in which a
  48.            error code describing the failure if there was one.
  49.  
  50.    RESULT
  51.        remote_entity - NULL if the given service cannot be found or access to
  52.            the service was denied.  Otherwise, a magic cookie describing the
  53.            service that you found.
  54.  
  55.    NOTES
  56.        All of the rules for FindEntity() apply here as well.  Please read the
  57.        Autodoc for FindEntity() for further information.
  58.  
  59.        Each SUCCESSFUL FindService() REQUIRES an associated LoseService().
  60.  
  61.    BUGS
  62.        Prior to V37.11 of services.library, FindService() would not
  63.        necessarily set FSVC_Error correctly on failure.
  64.  
  65.    SEE ALSO
  66.        nipc.library/FindEntity(), nipc.library/LoseEntity()
  67.  
  68. services.library/LoseService                     services.library/LoseService
  69.  
  70.    NAME
  71.        LoseService -- Free up any resources allocated from FindService().
  72.  
  73.    SYNOPSIS
  74.        LoseEntity(entity)
  75.                   A0
  76.  
  77.        VOID LoseEntity(struct Entity *)
  78.  
  79.    FUNCTION
  80.        This will merely free up any resources allocated with a successful
  81.        FindService() call.
  82.  
  83.    INPUTS
  84.        entity - A pointer to the Entity to use when communication with the
  85.            server process.
  86.  
  87.    RESULT
  88.        None
  89.  
  90.    NOTES
  91.        LoseService() should only be use on entities returned by FindService.
  92.        Attempting to use LoseService() on entities created by CreateEntity
  93.        is asking for trouble.
  94.  
  95.    BUGS
  96.        None known.
  97.  
  98.    SEE ALSO
  99.        FindService()
  100.  
  101.